//
//  CardIOPaymentViewControllerDelegate.h
//  Copyright (c) 2011-2012 Lumber Labs, Inc. All rights reserved.
//

#import <Foundation/Foundation.h>

@class CardIOPaymentViewController;
@class CardIOCreditCardInfo;
@class CardIOChargeResponse;

@protocol CardIOPaymentViewControllerDelegate<NSObject>

//
// card.io can be used to scan a card or to scan a card and charge a purchase.
//

//
// Scan only:
//
// Precisely one of userDidCancelPaymentViewController: or userDidProvideCreditCardInfo:inPaymentViewController: will be called.
// In either case, it is your responsibility to dismiss the CardIOPaymentViewController.
//

//
// Scan + charge:
//
// Precisely one of userDidCancelPaymentViewController: or paymentViewControllerDidFinish: will be called.
// In either case, it is your responsibility to dismiss the CardIOPaymentViewController.
//
// If the charge is successful, paymentViewController:didSucceedWithResponse: will be called.
// This is the correct place to provide the user with what they paid for.
// You should *not* dismiss the CardIOPaymentViewController from this method.
//
// If the charge fails in a way that *you, the developer* must fix, such as an invalid app token,
// paymentViewController:didFailWithError: will be called. (Charge failures due to user-controllable things
// like invalid or expired cards will be handled internally by card.io.)
// You should *not* dismiss the CardIOPaymentViewController from this method.
//

@required

// ALL: this method will be called if the user cancels the scan or transaction. You should dismiss the modal here.
- (void)userDidCancelPaymentViewController:(CardIOPaymentViewController *)paymentViewController;

@optional

// Note that either the first one or last three MUST be implemented, depending upon the use case.

// SCAN ONLY: implement this method to recieve charge results. You should dismiss the modal view controller here.
- (void)userDidProvideCreditCardInfo:(CardIOCreditCardInfo *)info inPaymentViewController:(CardIOPaymentViewController *)paymentViewController;

// SCAN + CHARGE: implment this method to be notified that the transaction has succeeded. You MUST NOT dismiss the modal view controller from this method.
- (void)paymentViewController:(CardIOPaymentViewController *)paymentViewController
       didSucceedWithResponse:(CardIOChargeResponse *)response;

// SCAN + CHARGE: implement this method to be notified that the transaction has failed. You MUST NOT dismiss the modal view controller from this method.
- (void)paymentViewController:(CardIOPaymentViewController *)paymentViewController
             didFailWithError:(NSError *)error;

// SCAN + CHARGE: implement this method to be notified that the charge view controller has finished. You should dismiss the modal view controller here.
- (void)paymentViewControllerDidFinish:(CardIOPaymentViewController *)paymentViewController;

@end